SERVEI DE WEBSERVICES

Introducció

Propòsit

Aquest servei permet configurar i usar de forma senzilla la infraestructura de Web Services en dues modalitats:

1. Exportació de serveis Java mitjançant Web Services.
2. Importació de Web Services externs, generació si cal de classes Java d'invocació.

L'enfocament d'aquest servei és el de simplificar tant la definició de Web Services a partir de serveis Java simples (que no tindran dependències amb la implementació particular de Web Services) així com la de facilitar la invocació a Web Services externs.

Context i Escenaris d'Ús

El Servei d'Integració de WebServices es troba ubicat dins els serveis continguts a la capa de Dades/Integració de Canigó.

Versions i Dependències

Les dependències descrites a la següent url son requerides per tal de compilar i fer funcionar el projecte:
Dependències Servei de WebServices

A qui va dirigit

Aquest document va dirigit als següents perfils:

1. Programador. Per conéixer l'ús del servei
2. Arquitecte. Per conéixer quins són els components i la configuració del servei
3. Administrador. Per conéixer cóm configurar el servei en cadascun dels entorns en cas de necessitat

Documents i Fonts de Referència

Descripció Detallada

Arquitectura i Components

Els components podem classificar-los en:

1. Interfícies i Components Genérics. Interfícies del servei i components d'ús general amb independència de la implementació escollida.
2. Implementació basada en Spring
   Es pot trobar tota la documentació JavaDoc i el codi font referent aquests components a les següents urls:

JavaDoc: http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-webservices/apidocs/index.html
Codi Font:  http://canigo.ctti.gencat.net/confluence/canigodocs/site/canigo2_0/canigo-services-webservices/xref/index.html

Instal.lació i Configuració

Instal.lació

La instal.lació del servei requereix de la utilització de la llibreria 'canigo-services-webservices' i les dependències indicades a l'apartat 'Introducció-Versions i Dependències'.

La instal- lació passa per modificar el pom.xml de l'aplicació per incloure les llibreries del Connector com a dependència.

<canigo.version>2.3.20</canigo.version>
<dependency>
  <groupId>canigo</groupId>
  <artifactId>canigo-services-webservices</artifactId>
  <version>${canigo.version}</version>
</dependency>

IMPORTANT En el cas de que es vulgui integrar aquest connector en una aplicació que disposi del connector de la PICA, és farà necessari afegir la següent exclusió a la dependència: <dependency> <groupId>canigo</groupId> <artifactId>canigo-services-webservices</artifactId> <version>${canigo.version}</version> <exclusions> <exclusion> <groupId>xmlbeans</groupId> <artifactId>xbean</artifactId> </exclusion> </dependency>

Configuració

La configuració del Servei d'Integració de Web Services implica els següents pasos:

1. Definir la implementació del Servei que s'usarà
2. Definir les interfícies pare d'exportació de serveis
3. Definir quins elements volem exportar com a WebServices i/o
4. Definir quins elements volem importar com a WebServices

Definició del Servei

Fitxer de configuració: canigo-services-webservices.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

En aquest pas indicarem el bean del servei de Web Services de Canigó i la implementació que es farà servir. En l'actualitat s'ofereix la implementació
'net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl'.

Podem definir les següents propietats:

Exemple:

<bean name="webServicesService"
     class="net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl"
    ...
</bean>

És a dir, si ens volem comunicar amb un Webservice ja existent farem ús de la propietat 'exportedInterfaces', mentre que si volem publicar un WebService usarem la propietat 'importedInterfaces'.
 

Definició de les Interfícies Pare d'Exportació i Importació de Serveis

Fitxer de configuració: canigo-services-webservices.xml
Ubicació proposada: <PROJECT_ROOT>/src/main/resources/spring

Usar el següent codi:

<bean abstract="true" id="exportedInterfaceDefinition"
      class="net.gencat.ctti.canigo.services.webservices.impl.ExportedInterfaceImpl"/>

<bean abstract="true" id="importedInterfaceDefinition"
      class="net.gencat.ctti.canigo.services.webservices.impl.ImportedInterfaceImpl"/>

Exemple:

<bean name="webServicesService" parent="WebServiceDefinition">
   <property name="exportedInterfaces">
	<list>
	   <bean parent="exportedInterfaceDefinition">
             <property name="name" value="testService"/>
	     <property name="implementation"
                       value="net.gencat.ctti.samples.webservices.TestServiceImpl"/>
	     <property name="localInterface"
                       value="net.gencat.ctti.samples.webservices.TestService"/>
 	   </bean>
	</list>
   </property>
   ...
</bean>

<servlet-mapping>
    <servlet-name>nom_servlet</servlet-name>
    <url-pattern>/ws/*</url-pattern>
</servlet-mapping>

• Disposem de la URL de definició del servei remot i de una interfície Java correcta que equival al WDSL. El servei web és de tipus "document" i no "rpc"

En aquest cas, definirem les següents propietats:

Exemple:

<bean parent="importedInterfaceDefinition">
   <property name="name" value="GoogleSearch" />
   <property name="serviceURL"
             value="http://localhost:8080/canigo-samples-webservices/testService"/>
   <property name="localInterface"
             value="net.gencat.ctti.samples.webservices.TestService"/>
</bean>

• Volem generar de forma automàtica les classes de comunicació a partir d'un WDSL extern. Veure l'apartat 'Eines de Suport-Generació de Classes a partir de WDSL' per consultar el procediment de generació d'aquestes classes. Definirem les següents propietats:

Utilització del Servei

Canigó exposa una interfície d'utilització, "net.gencat.ctti.canigo.webservices.WebServicesService", que amaga la implementació real utilitzada. D'aquesta forma diverses implementacions són fàcilment configurables en funció de les necessitats de l'aplicació. Aquesta interfície permet obtenir un webservice i treballar-hi posteriorment com si d'una classe normal es tractés.

La interfície té el següent aspecte:

package net.gencat.ctti.canigo.services.webservices;

/**
* Interface which allows the user to retrieve a Web Service interface from a given configuration
*/
public interface WebServicesService {
    ...
        public Object getWebService(String serviceName);
}

Eines de Suport

Generació de Classes a partir de WDSL

Per a generar les classes necessàries per importar un servei extern a partir d'un WDSL (veure apartat 'Configuració-Definició dels Serveis a Importar'), ho farem amb l'eina ANT, en un fitxer build.xml amb el següent contingut:

<project name="Generate client (Axis)" default="generate-client">

   <property name="output.dir" 	value="src"/>
   <property name="wsdl.file" 	value="resources/HolaMon.wsdl"/>
   <property name="lib" 	value="lib"/>

   <path id="axis.classpath">
     <fileset dir="${lib}">
       <include name="**/*.jar"/>
     </fileset>
   </path>

   <taskdef resource="axis-tasks.properties" classpathref="axis.classpath" />

   <target name="generate-client">
	<axis-wsdl2java output="${output.dir}" testcase="true"
		verbose="true" url="${wsdl.file}" >
	</axis-wsdl2java>
   </target>

</project>

• axis.jar
• axis-ant.jar
• commons-discovery.jar
• commons-logging.jar
• jaxrpc.jar
• log4j-1.2.8.jar
• saaj.jar
• wsdl4j.jar

En executar aquest fitxer es realitzarà de forma automàtica el següent procés:

1. S'examina el directori pre-establert on es troben els fitxers *.WSDL (en general, a src/main/wsdl). També es pot indicar la ubicació d'un WSDL remot mitjançant la seva URL.
2. Es generen les classes Java basades en Axis que equivalen als objectes remots descrits en el WSDL. Aquestes classes són generades al directori indicat sota la variable 'output.dir'. És responsabilitat del desenvolupador incloure les llibreries que requereixen les classes generades.

Integració amb Altres Serveis

Definició de les Excepcions Internacionalitzades

El servei defineix vàries excepcions amb diferents claus de missatges. Aquestes són:

canigo.services.WebServices.lookup_failed=lookup failed for {0}

canigo.services.WebServices.bad_bean_configuration=bad  configuration for {0}

canigo.services.WebServices.remote_method_invocation_failed=remote  method {0} failed for bean {1}

Preguntes Freqüents

java.lang.NoSuchMethodError

[10/03/06 17:18:32:130 CET] 2f75d693 ContextLoader E org.springframework.web.context.ContextLoader
TRAS0014I: The following exception was logged java.lang.NoSuchMethodError:javax.xml.namespace.
QName: method <init>(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V not found
    at     at org.codehaus.xfire.aegis.type.DefaultTypeMappingRegistry.<clinit>
    (DefaultTypeMappingRegistry.java:54).null(Unknown Source)
    at java.lang.Class.forName0(Native Method)
    at java.lang.Class.forName(Class.java(Compiled Code))
    at org.springframework.util.ClassUtils.forName(ClassUtils.java:88)
    at org.springframework.beans.factory.support.BeanDefinitionReaderUtils.
    createBeanDefinition(BeanDefinitionReaderUtils.java:65)
    at org.springframework.beans.factory.xml.DefaultXmlBeanDefinitionParser.
    parseBeanDefinitionElement(DefaultXmlBeanDefinitionParser.java:369)
...

<dependency>
    <groupId>stax</groupId>
    <artifactId>stax-api</artifactId>
    <version>1.0</version>
    <properties>
        <war.bundle>true</war.bundle>
    </properties>
</dependency>

• canigo-services-logging-2.3.x
• canigo-services-exceptions-2.3.x
• canigo-services-webservices-2.3.x
• xfire-all-1.2.6 (grup xfire)
• stax-api-1.0 (grup stax)
• wstx-asl-2.9.1 (grup woodstox)
• yom-1.0-alpha-2 (grup yom)
• jaxen-1.1-beta-8 (grup jaxen)
• jdom-1.0 (jdom)
• xbean-spring (xbean)
• wsdl4j-1.5.2 (wsdl4j)
• commons-beanutils-1.7
• spring-1.2.5      
  

Per totes elles assegurar-se de que s'incorporaran al war amb el tag '<war.bundle>true</war.bundle>'.

Websphere

A Websphere, una vegada fet el desplegament de l'aplicació tornar a seleccionar 'Applications>Enterprise Applications' i seleccionar l'aplicació. Des de la pestanya 'Configuration' realitzar els següents canvis: 

• Canviar el valor del camp 'Classloader Mode' a  'PARENT_LAST':
• Canviar el valor del camp 'WAR Classloader Policy' a 'Application'

Aplicar els canvis. En aquest moment iniciar l'aplicació i comprovar que no es dóna el missatge previ de conflicte.

WebLogic

En WebLogic podem fer el canvi directament
al fitxer 'weblogic.xml' introduint el valor 'true' en el tag
'prefer-web-inf-classes':

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE weblogic-web-app
PUBLIC "-//BEA Systems, Inc.//DTD Web Application 8.1//EN"
"http://www.bea.com/servers/wls810/dtd/weblogic810-web-jar.dtd">

<weblogic-web-app>
<container-descriptor>
    <prefer-web-inf-classes>true</prefer-web-inf-classes>
</container-descriptor>

</weblogic-web-app>

javax.xml.stream.FactoryConfigurationErrorApareix

l'Error 'javax.xml.stream.FactoryConfigurationError: Provider null could not be instantiated: java.lang.NullPointerException'

Si aquest error es dona en una aplicació desplegada al Servidor d'Aplicacions, tenim 2 possibles solucions:

a)       Crear un fitxer per definir la factoria 'XMLInputFactory' (opció més recomanada)

Crear un directori 'META-INF/services' (dins webapp si és una aplicació Web) i en aquest directori crear:

-         Fitxer 'javax.xml.stream.XMLInputFactory' (sense extensió)

El contingut d'aquest fitxer ha de ser 'com.ctc.wstx.stax.WstxInputFactory'.

Aquest comportament només funcionarà si no existeix el fitxer 'jaxp.properties' en el subdirectori 'jre\lib' de Java (veure següent alternativa). Així doncs, cal assegurar-se de que aquest fitxer (explicat en l'altra alternativa) no existeixi.

b)       Editar un fitxer 'jaxp.properties' a la localització del subdirectori 'jre\lib' amb la següent informació:

javax.xml.transform.TransformerFactory=org.apache.xalan.processor.TransformerFactoryImpl
javax.xml.parsers.SAXParserFactory=org.apache.xerces.jaxp.SAXParserFactoryImpl
javax.xml.parsers.DocumentBuilderFactory=org.apache.xerces.jaxp.DocumentBuilderFactoryImpl
javax.xml.stream.XMLInputFactory=com.ctc.wstx.stax.WstxInputFactory

Exemples

Exemple de Test

Classe: 'net.gencat.ctti.canigo.services.webservices.test.WebServicesServiceTest'

Per tractar-se d'un Test Unitari l'obtenció del servei es realitza de forma directa amb 'ClassPathXMLApplicationContext'. Cal recordar que podrem definir en els nostres beans de l'aplicació el servei sense necessitar d'accedir-hi amb 'ClassPathXmlApplicationContext'. En aquest cas és necessari per tractar-se d'un test unitari.

Exemple d'accés directe:

Obtenim el context Spring de test, aixo no cal fer-ho explícitament
en una aplicació web

BeanFactory beanFactory = new  ClassPathXmlApplicationContext("webServicesContext.xml");

WebServicesService service = (WebServicesService)  beanFactory.
getBean(WebServicesService.WEB_SERVICES_BEAN_FACTORY_KEY);

GoogleSearchPort google = (GoogleSearchPort) service.getWebService("GoogleSearch");
google.doGoogleSearch(...);

GoogleSearchPort google = WebServicesServiceUtils.getWebService(request,"GoogleSearch");
google.doGoogleSearch(...);

Exemple de Publicació d'un Servei de Codis Postals

En aquest exemple veurem com podem publicar un servei de forma senzilla mitjançant Canigó i XFire.

Suposem que volem publicar un servei que permet obtenir les localitats associades a un codi postal. Com a exemple pràctic i bastant real farem servir un servei extern ja existent de GeoNames.

Creació de la Interfície

En primer lloc creem una interfície Java en la que definim quins mètodes oferirem.

package net.gencat.ctti.canigo.samples.geo;
import java.util.Collection;

public interface GeoNamesService {

    public Collection getLocationsPostalCode(String aPostalCode);

}

Implementació de la Interfície

A continuació definim la implementació de la interfície:

public class GeoNamesServiceImpl implements GeoNamesService {

    public GeoNamesServiceImpl() {
        super();
        // TODO Auto-generated constructor stub
    }

    public Collection getLocationsPostalCode(String aPostalCode) {

        URL url;
        ArrayList list = new ArrayList();

        try {
            url = new URL("http://ws.geonames.org/postalCodeSearch?postalcode=" +
                   aPostalCode + "&country=ES&maxRows=10");
            try {
                SAXReader reader = new SAXReader();
                Document document = reader.read(url);
                // XES: Access with XPath
                List listNodes = document.selectNodes( "//geonames/code/name" );

                for ( Iterator i = listNodes.iterator(); i.hasNext(); ) {
                    DefaultElement element = (DefaultElement)i.next();
                    String text = element.getText();
                    list.add(text);
                    System.out.println(text);
                }
            } catch (Exception e) {
                // TODO Auto-generated catch block
                e.printStackTrace();
            }
        } catch (MalformedURLException e2) {
            // TODO Auto-generated catch block
            e2.printStackTrace();
        }
        return list;
    }

Publicació del Servei

<bean abstract="true" id="exportedInterfaceDefinition"
      class="net.gencat.ctti.canigo.services.webservices.impl.ExportedInterfaceImpl"/>

<bean name="webServicesService"
      class="net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl">

   <property name="exportedInterfaces">
      <list>
         <bean parent="exportedInterfaceDefinition">
           <property name="name" value="geoService"/>
           <property name="implementation"
                     value="net.gencat.ctti.canigo.samples.geo.GeoNamesServiceImpl"/>
           <property name="localInterface"
                     value="net.gencat.ctti.canigo.samples.geo.GeoNamesService"/>
         </bean>
      </list>
   </property>
</bean>

• name: Nom del servei publicat. Corresponent a cóm es publicarà el servei dins el WSDL
• implementation: Nom de la classe implementació
• localInterface: Nom de la interfície
  
  Tipus de Dades
  En la utilització dels WebServices cal tenir en compte que hi ha tipus de dades que no poden ser enviats i rebuts si no s'especifica de forma adicional cóm el Servidor pot tractar les peticions.
  Si definim una col.lecció per exemple (com en aquest cas exemple), haurem d'especificar quin tipus de dades contindrà internament per saber com passar les dades de retorn. Per a aconseguir-ho només cal que definim un fitxer amb el nom de la interfície i a continuació l'extensió 'aegis.xml' i ubicar-lo en el mateix lloc que la interfície.
  
  En l'exemple, definim el següent contingut:
  

  <?xml version="1.0" encoding="UTF-8" ?>
  <mappings>
      <mapping>
          <method name="getLocationsPostalCode">
              <return-type componentType="java.lang.String"/>
          </method>
      </mapping>
  </mappings>

  
  
  
  Això vol dir que la col.lecció de retorn del mètode 'getLocationsPostalCode' conté elements de tipus String.
  Per a informació d'altres mapejos consultar la url 'http://xfire.codehaus.org/Aegis+Binding'.
  
  

  Desplegament del Servei i Prova d'Accés al WSDL

A continuació, podem crear un war i desplegar-lo en un servidor d'aplicacions.
Una vegada desplegat podem accedir al seu wsdl amb la següent url:

http://localhost:9080/<nom context app>/geoService?wsdl

El nom 'geoService' correspon al valor de l'atribut 'name' que hem especificat prèviament al fitxer de configuració.



Cóm es pot veure el WSDL s'ha generat de forma automàtica.

Accés des d'un Client

Si volem accedir al servei publicat podem fer ús de la importació seguint els següents pasos:

1)      Definició en el fitxer de configuració de la importació

<bean abstract="true" id="importedInterfaceDefinition"
      class="net.gencat.ctti.canigo.services.webservices.impl.ImportedInterfaceImpl"/>

<bean name="webServicesService"
      class="net.gencat.ctti.canigo.services.webservices.impl.WebServicesServiceImpl">
   <property name="importedInterfaces">
      <list>
          <bean parent="importedInterfaceDefinition">
                <property name="name" value="geoNamesService" />
                <property name="serviceURL"
                          value="http://localhost:9080/canigo-samples-geo/geoService"/>
                <property name="localInterface"
                          value="net.gencat.ctti.canigo.samples.geo.GeoNamesService"/>
         </bean>
     </list>
   </property>

• name: Nom que ens permetrà a partir del mètode 'getService' del bean 'webServicesService' obtenir una referència a la interfície (definida a la propietat 'localInterface' com si d'una classe local es tractés.

• localInterface: Nom de la interfície serviceUrl: Url del servei corresponent a la url publicada prèviament. Exemple: http://localhost:9080/<nom context app>/geoService.
  

2)     Accés des d'una classe

Una vegada definit això l'accés seria tan simple com l'exemple mostrat a continuació:

GeoNamesService geoService = (GeoNamesService)webServicesService.getWebService("geoNamesService");
Collection locations = geoService.getLocationsPostalCode("08031");

<bean id="geoNamesService" factory-bean="webServicesService"
      factory-method="getWebService">
   <constructor-arg><value>geoNamesService</value></constructor-arg>
</bean>

Exemple d'ús de Ajax amb el Servei Publicat

NOTA: Tot i no ser objectiu del present document es mostra en aquest apartat com podem utilitzar el servei 'geoNamesService' (que permet comunicar-se amb el WebService) per presentar les poblacions a l'usuari segons el codi postal introduit usant Ajax:

En primer lloc, publicarem el servei definit en el pas anterior (<bean id="geoNamesService" factory-bean="webServicesService" ...) introduint al fitxer 'src/main/resources/dwr/dwr.xml' que volem des del client Web accedir a aquest servei:

<create creator="spring" javascript="geoNamesService">
    <param name="beanName" value="geoNamesService"/>
</create>

<script src="<c:url value="/AppJava/dwr/interface/geoNamesService.js"/>">
</script>

<script>
var locations;

  function closeSuggestBox() {
    $('suggestBoxElement').innerHTML = '';
    $('suggestBoxElement').style.visibility = 'hidden';
  }

  // remove highlight on mouse out event
  function suggestBoxMouseOut(obj) {
    document.getElementById('pcId'+ obj).className = 'suggestions';
  }

  // the user has selected a place name from the suggest box
  function suggestBoxMouseDown(obj) {
    closeSuggestBox();
    var placeInput = $('city');
    placeInput.value = locations[obj];
  }
var PostalCodeWatcher = Class.create();

PostalCodeWatcher.prototype = {

       initialize: function(field) {
            this.field = $(field);
            this.field.onchange = this.getLocationsPostalCode.bindAsEventListener(this);
               },

           getLocationsPostalCode: function(evt){
               if ($F(this.field)) {
               geoNamesService.getLocationsPostalCode(
                        $F(this.field),{
                        callback:function(dataFromServer) {updateLocations(dataFromServer);
                        },
                           timeout:5000
                       }
                   );
               }
           }
    };

    var watcher = new PostalCodeWatcher('zip');

  // function to highlight places on mouse over event

  function suggestBoxMouseOver(obj) {
    document.getElementById('pcId'+ obj).className = 'suggestionMouseOver';
  }

  function updateLocations(dataFromServer) {
         $('suggestBoxElement').style.visibility = 'visible';
         $('suggestBoxElement').innerHTML = '<small><i>loading ...</i></small>';

         locations = dataFromServer;
         //alert(DWRUtil.toDescriptiveString(dataFromServer,1));
         if (locations.length > 1) {
                $('suggestBoxElement').style.visibility = 'visible';
             var suggestBoxHTML  = '';
             // iterate over places and build suggest box content
             for (i=0;i< locations.length;i++) {
               suggestBoxHTML += "<div class='suggestions' id=pcId" + i + "
               onmousedown='suggestBoxMouseDown(" + i + ")'
               onmouseover='suggestBoxMouseOver(" +  i +")'
               onmouseout='suggestBoxMouseOut(" + i +")'> " + locations[i] +'</div>';
             }
                $('suggestBoxElement').innerHTML = suggestBoxHTML;
         } else {
             if (dataFromServer.length == 1) {
               $("city").value=locations[0];
             }
           closeSuggestBox();
         }
  }

</script>

• Definició d'una classe on s'especificarà el comportament

• ?El mètode initialize defineix els valors de la instància de la classe.

• En el valor del camp 'onchange' utilitzem la funció 'bindAsEventListener' per lligar la funció 'getLocationsPostalCode de la classe' com a listener de l'event (en el moment que canvii el valor del component)
  

  this.field.onchange = this.getLocationsPostalCode.bindAsEventListener(this);

  
  
  
  
  
• ? El mètode 'getLocationsPostalCode' defineix el tractament de l'event  i és on es farà la crida a la funció del servidor mitjançant Ajax.

• ? Crida a la instància publicada amb DWR (segons s'havia definit al fitxer dwr.xml com 'javascript="geoNamesService"') a un mètode concret passant com a paràmetre el valor del camp
  

NOTA: La funció $F() de prototype permet obtenir el valor de qualsevol tipus de input (enlloc d'haver d'usar diferents funcions segons el tipus de component).

• ' De forma adicional als paràmetres de la funció cridada podem incorporar més paràmetres. El primer paràmetre 'callback' ens permet especificar quina funció serà cridada quan la crida a la funció finalitzi. El segon paràmetre permet especificar quin timeout de la crida volem utilitzar. Dins el callback s'especifica la crida a la funció 'updateLocations(dataFromServer)' on el paràmetre 'dataFromServer' seran  les dades de retorn de la funció.
  

  // function to highlight places on mouse over event
  
    function suggestBoxMouseOver(obj) {
      document.getElementById('pcId'+ obj).className = 'suggestionMouseOver';
    }
  
    function updateLocations(dataFromServer) {
           $('suggestBoxElement').style.visibility = 'visible';
           $('suggestBoxElement').innerHTML = '<small><i>loading ...</i></small>';
  
           locations = dataFromServer;
           //alert(DWRUtil.toDescriptiveString(dataFromServer,1));
           if (locations.length > 1) {
                  $('suggestBoxElement').style.visibility = 'visible';
               var suggestBoxHTML  = '';
               // iterate over places and build suggest box content
               for (i=0;i< locations.length;i++) {
                 suggestBoxHTML += "<div class='suggestions' id=pcId" + i + "
                 onmousedown='suggestBoxMouseDown(" + i + ")'
                 onmouseover='suggestBoxMouseOver(" +  i +")'
                 onmouseout='suggestBoxMouseOut(" + i +")'> " + locations[i] +'</div>';
               }
                  $('suggestBoxElement').innerHTML = suggestBoxHTML;
           } else {
               if (dataFromServer.length == 1) {
                 $("city").value=locations[0];
               }
             closeSuggestBox();
           }
    }
  
  </script>

  
  
  
  

Degut a que la funció ens retorna una col.lecció de poblacions es tracten els casos d'un valor retornat -es copiarà directament al component destí- o de més d'un valor -es mostraran vàries capes per simular una selecció a l'usuari.

Per últim, podem definir l'estil d'aquestes seleccions:

<style>

  #suggestBoxElement {border: 1px solid #8FABFF; visibility:hidden; text-align: left;
  white-space: nowrap; background-color: #eeeeee;}

  .suggestions { font-size: 14;background-color: #eeeeee;  }

  .suggestionMouseOver { font-size: 14;background: #3333ff; color: white;  }

</style>